← 返回 Game Development / Unity / MagicGameHarness

2026-08-21 ·36 min

Magic Game Harness vs SMAPI（Stardew Valley Modding Platform）

这不是 spec 实现笔记，是对比分析笔记——通过”现有的 mod平台怎么做的”来理解 magic-game-harness-unity 的设计选择。

SMAPI = Stardew Modding API，是 Stardew Valley 游戏的官方 mod 平台，2016 年至今维护。已经有 5000+ mod 跑在它上面——这是已经被验证可行的 mod平台设计。

0. 为什么对比 SMAPI？

SMAPI 是最成功的商业游戏 mod 平台之一——

一个 mod 作者拿不到 Stardew Valley 源码
一个玩家一键安装/卸载 mod
一个存档跨多个 mod 仍能工作
5000+ mod 在生产中——说明这套机制在真实玩家手里工作得很好

而 magic-game-harness-unity 试图做的事：

与 SMAPI 几乎完全相同，只是更现代、更严格、面向 Unity + HybridCLR

所以对比 SMAPI 非常有价值：

SMAPI 已经踩过的坑 → 这个项目可以主动避开
SMAPI 没解决的问题 → 这个项目通过 spec 设计主动解决
SMAPI 的好设计 → 这个项目复用

1. SMAPI 是什么？快速回顾

1.1 架构

1
StardewModdingAPI.exe   ← 玩家启动的是它，不是 Stardew Valley.exe
2
   │
3
   ├── 加载游戏程序集，接管入口
4
   │
5
   ├── SMAPI core
6
   │     ├── AssemblyLoader  ── 用 Mono.Cecil 重写 mod IL，再 Assembly.Load
7
   │     ├── Mod Loader      ── 读 manifest.json、拓扑排序依赖、实例化 IMod
8
   │     ├── Event system    ── 把游戏循环包装成 SMAPI 事件
9
   │     └── Content API     ── 拦截资产加载，供 mod 编辑/替换
10
   │
11
   ├── mod-1.dll  (可选地自己用 HarmonyLib 打 patch)
12
   ├── mod-2.dll
13
   └── ...

关键点：SMAPI 不是游戏的一部分——它是一个第三方工具，反过来把游戏加载进自己的进程。

⚠️ 关于加载机制的一个常见误解：SMAPI 加载 mod 靠的是 Mono.Cecil 重写 IL + Assembly.Load，不是 MonoMod / Harmony 的运行时 patch。

那个重写步骤（社区俗称 “the rewriter”）的作用是抹平差异：Stardew 有多平台构建、XNA 与 MonoGame 两套底层、以及跨游戏版本的方法签名变动。SMAPI 在加载每个 mod DLL 前用 Cecil 扫描它的 IL，把过时的类型引用和方法调用改写成当前平台/版本正确的形式。这就是为什么很多老 mod 在游戏更新后不用重新编译还能跑。

Harmony 是各个 mod 自己按需用的（Harmony.CreateAndPatchAll(...)），SMAPI 只是打包提供。它不是加载机制。

这与 magic-game-harness-unity 的根本不同：

维度	SMAPI	magic-game-harness-unity
框架提供者	第三方（SMAPI 团队）	游戏本体（mimizmi）
代码位置	外部启动器 + 运行时接管	原生集成（`Game.Bootstrap` 就是游戏的组合根）
Mod 加载方式	Mono.Cecil 重写 IL + `Assembly.Load`	HybridCLR 加载热更 DLL（解释 + AOT 混合执行）
兼容性做法	加载时改写 mod 去适配游戏	加载前校验声明，不匹配就拒绝加载
Mod API 稳定性	SMAPI 自己的 API（`IMod` / `IModHelper` / 事件体系）是正式的、有版本有文档、有弃用周期的；不官方的是游戏本体内部实现——那才是 mod 靠反编译摸索、靠 Harmony patch 去改的部分	官方维护的稳定契约（`Game.ModApi`），且没有 patch 游戏内部这一层
Mod 兼容保证	”尽量不破坏” + 中心化兼容性数据库	显式版本号 + `FrameworkCompatibility` 四维度，写进 manifest

第 4 行才是最本质的差异。 SMAPI 因为拿不到游戏源码，只能事后改写 mod 去适配；harness 因为框架就是游戏本体，可以事前要求声明、不匹配直接拒绝。

前者是”尽力而为的兼容”——好处是老 mod 常常自动就活了，坏处是没人能保证它语义上还对（IL 改写只保证不崩，不保证行为没变）。后者是”可证明的兼容”——好处是不匹配会在加载前被拒，坏处是对 Mod 作者的约束严格得多（见 §13.1 的门槛风险）。

第 5 行原先写成”SMAPI 的 Mod API 是反编译推出来的（不官方）“，这混淆了两层：SMAPI 给 mod 用的 API 是正经 API；被反编译的是星露谷本体。这个区分很重要，否则会得出”harness 比 SMAPI 有官方 API”这种错误结论——两者都有官方 API，差别在于 harness 的 API 背后没有一个需要 patch 的黑盒游戏。

1.2 SMAPI 的核心组件

组件	归属	作用
SMAPI core	SMAPI	mod 发现与加载、生命周期、事件分发、日志
AssemblyLoader（Mono.Cecil）	SMAPI	加载前重写 mod IL，抹平平台/版本差异
Mod API（`IMod`、`IModHelper`、事件）	SMAPI	暴露给 mod 的正式契约
Content API（`IAssetEditor` / `IAssetLoader` 及其后继）	SMAPI	让 mod 拦截、编辑、替换游戏资产
HarmonyLib	第三方库，SMAPI 打包提供	各 mod 自行运行时 patch 游戏方法
Content Patcher	第三方 mod（Pathoschild 作）	让不会写代码的作者用 JSON 声明式地改内容

⚠️ 两处需要澄清：

MonoMod 不是 SMAPI 的独立组件。 Harmony 2.x 内部构建在 MonoMod.Core 之上，但那是 Harmony 的实现细节；SMAPI 自己的重写层用的是 Mono.Cecil。

Content Patcher 是一个第三方 mod，不是 SMAPI 核心。 而且它并不”编辑 XNB 文件”——它工作在 SMAPI 的 content API 之上，操作的是加载后的资产对象。直接改 XNB 是更早期 XNB-hack 时代的做法，正是 Content Patcher 用来取代的东西（那种做法要求玩家覆盖游戏文件，多个 mod 改同一个文件必然冲突）。

这个区分对本篇的论点有意义：Content Patcher 的存在本身就说明”声明式内容修改”是一个足够大的需求，大到值得社区在框架之外再造一层。 harness 把 Content 列进 spec §11.1 的 11 个命名空间之一（虽然还是空目录），是把这个教训吸收进了框架层。

2. 概念对照表

概念	SMAPI	magic-game-harness-unity
Mod 入口	`IMod.Entry(IModHelper)`	`IModule.ActivateAsync(IModuleContext, CancellationToken)`
Mod 描述	`manifest.json`（含 id/version/依赖/兼容性）	`ModuleDescriptor`（含 CapabilityRequirement/Provision）
依赖系统	manifest 里写 `"Dependencies": ["SpaceCore"]`	Capability 键 + 版本（`"framework.physics-2d": "1.x"`）
Mod 元数据	`manifest.json`	`ModuleDescriptor` (代码) + `manifest.json` (分发)
Mod 通信	静态 helper 方法 + 事件总线	Capability 接口 + 版本协商
Mod 加载顺序	按依赖 + manifest 声明	Topological sort by capability graph
Mod 沙箱	❌ 无（full trust）	❌ 无（spec 5.2 明确）
存档兼容	❌ 部分 mod 写存档破坏兼容	✅ per-world Lockfile + schema migration
官方版本	跟着游戏版本走	`FrameworkCompatibility` 4 维度检查
跨 mod 合约	❌ 没有强制（mod 作者自己协调）	✅ Contract-only assembly 机制

3. 关键设计决策对比

3.1 决策 A：Mod 加载机制

SMAPI

1
// SMAPI 内部：反射加载 mod dll
2
var assembly = Assembly.LoadFrom(modDllPath);
3
var modType = assembly.GetTypes()
4
    .Single(t => typeof(IMod).IsAssignableFrom(t));
5
var mod = (IMod)Activator.CreateInstance(modType);
6
mod.Entry(modHelper);

问题：

❌ 反射加载 → 首次启动慢（JIT + 反射 metadata 处理）
❌ 没有 mod 完整性校验（dll 可被篡改）
❌ 加载顺序由 manifest 声明，但没有真正的版本约束——"SpaceCore": "1.0.0" 只是字符串比较

magic-game-harness-unity

1
// 推断的实现（Context Runtime 未实现）
2
var assembly = HybridCLR.RuntimeApi.LoadAssembly(dllBytes);
3
var sha256 = ComputeSha256(dllBytes);
4
if (sha256 != manifest.Artifacts.Sha256) throw new ModCorruptedException();
5
// ↑ 加载时立即校验 hash
6

7
// 按 capability graph topological sort
8
var sortedMods = TopologicalSort(dependencyGraph);
9
foreach (var mod in sortedMods)
10
{
11
    if (!AllRequiredCapabilitiesResolved(mod)) continue;  // optional 可以缺失
12
    await mod.ActivateAsync(context, cancellationToken);
13
}

改进：

✅ HybridCLR 编译加载 → 快（不需要反射 metadata）
✅ Hash 校验 → 防篡改
✅ Capability 版本协商 → 真正的版本约束

3.2 决策 B：Mod 通信

SMAPI

Mod 之间通信主要靠：

1
// Mod A 注册 API
2
public class MyMod : IMod
3
{
4
    public void Entry(IModHelper helper)
5
    {
6
        // 直接挂在 helper 上
7
        helper.Events.GameLoop.SaveLoaded += OnSaveLoaded;
8

9
        // 或者用 SMAPI 的事件总线
10
        helper.Events.Player.Warped += OnPlayerWarped;
11
    }
12
}
13

14
// Mod B 监听
15
public class OtherMod : IMod
16
{
17
    public void Entry(IModHelper helper)
18
    {
19
        helper.Events.GameLoop.SaveLoaded += (s, e) => { /* ... */ };
20
    }
21
}

问题：

❌ 没有类型检查——A 改了事件签名，B 编译时发现不了
❌ 没有版本协商——A 升级到 2.0 加了新参数，B 没更新就崩
❌ 事件总线是全局的——任何 mod 可以监听任何事件 → 性能 + 调试困难

magic-game-harness-unity

Mod 之间通信靠 capability：

📌 代码约定：下面这段（以及本篇后续所有 ctx.RegisterCapability<...> / ctx.GetCapability<...>）是占位伪代码，当前代码库中不存在。IModuleContext 目前只有 ModuleId 和 Diagnostics 两个属性，而且 Module_context_is_not_an_unrestricted_service_locator 明确禁止泛型方法——真实形态只能是 RegisterCapability(CapabilityKey, CapabilityVersion, object) 这样的非泛型签名，返回 IDisposable 句柄。详见 06-Mod-Distribution.md §1.5。这不影响本节的论点（SMAPI 靠运行时握手 vs harness 靠声明式契约），只影响语法。

1
// Mod A 提供 capability（伪代码）
2
public async Task<ModuleOperationResult> ActivateAsync(IModuleContext ctx, CancellationToken ct)
3
{
4
    ctx.RegisterCapability<IGameRules>(new AlphaRules());
5
    // ↑ 注册 + 版本固定
6
    return ModuleOperationResult.Success();
7
}
8

9
// Mod B 消费 capability
10
public async Task<ModuleOperationResult> ActivateAsync(IModuleContext ctx, CancellationToken ct)
11
{
12
    var rules = ctx.GetCapability<IGameRules>("game.alpha-rules");
13
    // ↑ 类型安全的查找 + 编译期类型检查
14
    rules.SomeMethod();
15
}

改进：

✅ 类型安全——IGameRules 是 contract dll 里的接口，编译期就检查
✅ 版本协商——capability key + version 锁定，spec 第 11 节”explicit compatibility”
✅ 能力是显式的——RequiredCapabilities + ProvidedCapabilities 在 descriptor 里说清楚

3.3 决策 C：存档兼容性

SMAPI

SMAPI 不直接管存档——mod 自己管。问题：

❌ Mod A 写了存档 → Mod A 卸载 → 存档变成不可用数据
❌ Mod A 升级改了字段名 → 旧存档读不出来
❌ 没有 per-world mod 集合——全局 mod 列表改变会破坏存档

SMAPI 实际上”无解”——只能靠 mod 作者自己写 schema migration 代码。

magic-game-harness-unity

spec 第 3.1 节明文要求：

Preserve save data when a mod is missing, disabled, upgraded, or reinstalled.

机制：

Per-World Lockfile（spec 第 3.1 节）——存档绑 Lockfile，不绑当前 mod 集合
Schema migration（spec 第 11 节命名空间有 Storage，未实现）——mod 可以声明 schema 转换
Missing content handling（spec 第 10.6 节）——mod 缺失时，世界里的”该 mod 创建的内容”不会被自动删除，而是保留 + 标记 missing

改进：

✅ Lockfile 冻结 → 即使 mod 升级，存档加载的还是旧版本 mod
✅ Schema migration framework（计划中）→ 自动升级存档
✅ Missing content 保留 → 玩家可以再装回 mod 恢复世界

3.4 决策 D：Mod 元数据 / Manifest

SMAPI

1
// SMAPI manifest.json（真实字段集）
2
{
3
    "Name": "Crops Anytime Anywhere",
4
    "Author": "Pathoschild",
5
    "Version": "1.0.0",
6
    "Description": "Lets you plant crops in any season and location.",
7
    "UniqueID": "Pathoschild.CropsAnytimeAnywhere",  // ← 类似 ModuleId
8
    "EntryDll": "CropsAnytimeAnywhere.dll",          // ← 必填：入口程序集
9
    "MinimumApiVersion": "3.0.0",                    // ← 只约束 SMAPI 版本
10
    "Dependencies": [
11
        { "UniqueID": "SpaceCore", "MinimumVersion": "1.0.0", "IsRequired": true }
12
    ],
13
    "UpdateKeys": [ "Nexus:1598" ]                   // ← 更新检查用
14
}

⚠️ SMAPI 的 manifest 里没有”游戏版本兼容性”字段。 没有 Compatibility、没有 GameVersion。

游戏版本兼容性由 SMAPI 中心化维护的 mod 兼容性数据库负责——SMAPI 启动时拉取这份数据，据此提示”这个 mod 在当前游戏版本下已知会崩”。

这不是疏漏，是结构决定的。 SMAPI 是第三方框架，它没有权力要求 mod 作者去声明一个 SMAPI 自己都不拥有的版本轴——游戏版本由 ConcernedApe 说了算，且随时可能变。唯一可行的办法就是事后由第三方（SMAPI 团队 + 社区）集中记录”哪个 mod 在哪个游戏版本下坏了”。

而 harness 因为框架就是游戏本体，可以把这件事前置成 manifest 的必填字段——这正是 FrameworkCompatibility 四个维度的意义。下面的对比表因此比”SMAPI 是半自由文本”这种说法有力得多：不是 SMAPI 做得潦草，是它结构上做不到。

对比 magic-game-harness-unity 的 manifest（已推测）：

1
{
2
    "manifestVersion": 1,
3
    "id": "author.alpha-rules",                        // ModuleId
4
    "version": "1.0.0",                                // ModuleVersion (SemVer)
5
    "dependencies": [
6
        {
7
            "id": "framework.physics-2d",                // CapabilityKey
8
            "version": "1.x",                            // CapabilityVersion
9
            "type": "capability"
10
        }
11
    ],
12
    "provides": [
13
        {
14
            "id": "game.alpha-rules",                    // CapabilityKey
15
            "version": "1.0.0",                          // CapabilityVersion
16
            "type": "capability"
17
        }
18
    ],
19
    "permissions": [
20
        "world.modify", "world.read", "ui.overlay"
21
    ],
22
    "compatibility": {                                  // FrameworkCompatibility 4 维度
23
        "gameBuild": "framework.phase1_dev-1",
24
        "modApi": "0.1.0",
25
        "networkProtocol": 1,
26
        "contentCompatibility": 1
27
    },
28
    "artifacts": {
29
        "dll": "mod-author-alpha.dll",
30
        "contentCatalog": "content-author-alpha/catalog.json",
31
        "size": 4582912,
32
        "sha256": "abc123..."
33
    }
34
}

对比：

字段	SMAPI	magic-game-harness-unity
Mod ID	`UniqueID: "Pathoschild.CropsAnytimeAnywhere"`（约定俗成的 `Author.Name`，无格式强制）	`id: "author.alpha-rules"`（`ModuleId.Parse` 强制：小写、点分段、段首字母、≤128）
Version	字符串，SMAPI 自己解析成 `ISemanticVersion`（它的语义比 SemVer 2.0.0 略宽松）	`SemanticVersion` 严格 SemVer 2.0.0，precedence 与 identity 分离
Dependencies	`UniqueID` + `MinimumVersion`（只有下界）	Capability + 版本（当前是精确版本，区间类型尚未实现——见 06 §1.5）
Provides	❌ 不显式（mod 之间靠 `IModHelper.ModRegistry.GetApi()` 运行时握手）	✅ `ProvidedCapabilities` 显式声明
Permissions	❌ 没有	✅ spec 规划中的显式声明（当前未实现）
游戏兼容性	❌ 不在 manifest 里，由中心化兼容性数据库维护	✅ 4 维度独立写进 manifest（GameBuild / ModApi / NetworkProtocol / Content）
Artifact hash	❌ 没有（分发靠 Nexus/ModDrop 等平台自己保证）	✅ spec 规划 SHA256

关键差异不在”谁的字段多”，而在”信息属于谁”：

SMAPI 能强制的只有它自己拥有的那条轴（MinimumApiVersion）。游戏版本、artifact 完整性、mod 提供什么 API——这些它都无权要求，只能靠社区数据库、分发平台、运行时握手来补。
harness 拥有全部四条轴，所以能把它们全部前置到 manifest，在安装/加载前就做完机器校验。

代价是对称的：SMAPI 的 mod 作者填 5 个字段就能发布，harness 的作者要填四维兼容性 + 能力声明 + 权限。这是 spec §6 原则 12”Professional authoring, consumer simplicity”的直接体现——复杂度被刻意集中到 SDK 和作者侧，换玩家侧的一键安装与可恢复性。

3.5 决策 E：Mod 沙箱

SMAPI

完全无沙箱——mod 拿到：

✅ 整个 Stardew Valley 内部 API（包括私有方法）
✅ 文件系统访问
✅ 网络访问
✅ 进程访问

实际上 SMAPI 是通过 Harmony “patch” Stardew 的代码——mod 可以改任何方法的 IL。

问题：

❌ 恶意 mod 可以读玩家所有文件
❌ 恶意 mod 可以上传玩家数据
❌ 良性 mod 也会因为版本不兼容而崩溃

magic-game-harness-unity

spec 第 5.2 节明文：

the AOT kernel and AOT core rules are a correctness boundary for conforming modules, not a security boundary against a malicious host or a modified client.

也就是说：mod 可以：

❌ 不能访问私有程序集（编译期就阻止）
❌ 不能访问文件系统（除非显式 permission）
❌ 不能访问网络（除非显式 permission）
✅ 可以访问 IGameRules 这种 interface
✅ 可以访问 capabilities
✅ 仍然是 full trust——可以伪造游戏状态

与 SMAPI 的区别：

magic-game-harness-unity 的 mod 更难写恶意 mod（SDK 限制 + 编译期阻止私有 API 访问）
但 也不是真沙箱——spec 明确说这是 correctness boundary 不是 security boundary

4. SMAPI 已经解决的，magic-game-harness-unity 已经借鉴

4.1 借鉴 #1：Mod Helper 模式

SMAPI 的 IModHelper 把”框架服务”打包成 helper：

1
// SMAPI 风格
2
public class MyMod : IMod
3
{
4
    public void Entry(IModHelper helper)
5
    {
6
        helper.Events.GameLoop.SaveLoaded += ...;
7
        helper.Content.Load<Texture2D>(".../texture.png");
8
        helper.Reflection.GetField<int>(someObj, "fieldName");
9
        // ...
10
    }
11
}

magic-game-harness-unity 等价物是 IModuleContext——但更窄：

1
// magic-game-harness-unity 风格
2
public async Task<ModuleOperationResult> ActivateAsync(IModuleContext ctx, CancellationToken ct)
3
{
4
    ctx.Diagnostics.Report(new ModuleDiagnostic(...));
5
    // ↑ 只有 Diagnostics，没有 Reflection/Content Helper
6
}

取舍：magic-game-harness-unity 故意只暴露最少——Mod 作者应该通过 capability 接口拿到其他服务，而不是通过万能 helper。

这是进步：SMAPI 的 IModHelper.Reflection.GetField 让 mod 可以 hack 私有字段——magic-game-harness-unity 直接禁掉这条路。

4.2 借鉴 #2：Mod 配置文件位置约定

SMAPI 约定 mod 配置文件放：

1
~/.config/StardewValley/<game-version>/<mod-UniqueID>/config.json

magic-game-harness-unity 类似（spec 第 11 节 Storage）：

1
<save-location>/<world-id>/mods/<mod-id>/storage.json

好处：玩家备份/迁移/卸载时 mod 数据跟着走。

4.3 借鉴 #3：Mod 版本独立

SMAPI 和 magic-game-harness-unity 都让 Mod 版本和游戏版本独立——mod 升级不强制游戏升级。